<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.5"/>
<title>NDK Programmer&#39;s Guide: ndk-build</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">NDK Programmer&#39;s Guide
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.5 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;"
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('md_3__key__topics__building__chapter_1-section_8_ndk-build.html','');});
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title">ndk-build </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p><a href="#int">Internals</a><br/>
 <a href="#ifc">Invoking from the Command Line</a><br/>
 <a href="#ife">Invoking from Eclipse</a><br/>
 <a href="#6432">64-bit and 32-bit toolchains</a><br/>
 <a href="#req">Requirements</a><br/>
</p>
<p><a class="anchor" id="int"></a> </p>
<h2>Internals</h2>
<p>ndk-build is a tiny shell script introduced in Android NDK r4. Its purpose
is simply to invoke the right NDK build script; it is equivalent to: </p>
<pre class="fragment">$GNUMAKE -f &lt;ndk&gt;/build/core/build-local.mk
&lt;parameters&gt;
</pre><p><code>$GNUMAKE</code> points to GNU Make 3.81 or later, and
<code>&lt;ndk&gt;</code> points to your NDK installation directory. You can use
this information to invoke ndk-build from other shell scripts, or even your own
make files.</p>
<p><a class="anchor" id="ifc"></a> </p>
<h2>Invoking from the Command Line</h2>
<p>ndk-build lives in the top-level directory of the NDK. To run it from the
command line, invoke it while in or under your application project directory.
For example: </p>
<pre class="fragment">cd &lt;project&gt;
&lt;ndk&gt;/ndk-build
</pre><p>In this example, <code>&lt;project&gt;</code> points to your
project’s root directory, and <code>&lt;ndk&gt;</code> is the directory where
you installed the NDK. Per “Getting Started,” you can add $NDK to your PATH
to avoid having to type the whole filepath every time you use ndk-build.
Alternatively, you can create an alias.</p>
<p><a class="anchor" id="options"></a> </p>
<h3>Options</h3>
<p>All parameters to ndk-build are passed directly to the underlying GNU Make
command that runs the NDK build scripts. Combine <code>ndk-build</code> and
options in the form <code>ndk-build &lt;option&gt;</code>. For example: </p>
<pre class="fragment">$ ndk-build clean
</pre><p>The following options are available:</p>
<ul>
<li><code>clean</code><ul>
<li>Clean all generated binaries.</li>
</ul>
</li>
<li><code>V=1</code><ul>
<li>Launch build, and display build commands.</li>
</ul>
</li>
<li><code>-B</code><ul>
<li>Force a complete rebuild.</li>
</ul>
</li>
<li><code>-B V=1</code><ul>
<li>Force a complete rebuild and display build commands.</li>
</ul>
</li>
<li><code>NDK_LOG=1</code><ul>
<li>Display internal NDK log messages (used for debugging the NDK itself).</li>
</ul>
</li>
<li><code>NDK_DEBUG=1</code><ul>
<li>Force a debuggable build (<a href="#dvr">see below</a>).</li>
</ul>
</li>
<li><code>NDK_DEBUG=0</code><ul>
<li>Force a release build (<a href="#dvr">see below</a>).</li>
</ul>
</li>
<li><code>NDK_HOST_32BIT=1</code><ul>
<li>Always use toolchain in 32-bit mode (see below).</li>
</ul>
</li>
<li><code>NDK_APPLICATION_MK=&lt;file&gt;</code><ul>
<li>Build, using a specific <code>Application.mk</code> file pointed to by the
<code>NDK_APPLICATION_MK</code> variable.</li>
</ul>
</li>
<li><code>-C &lt;project&gt;</code><ul>
<li>Build the native code for the project path located at
<code>&lt;project&gt;</code>. Useful if you don't want to <code>cd</code> to it
in your terminal.</li>
</ul>
</li>
</ul>
<p><a class="anchor" id="ife"></a> </p>
<h2>Invoking from Eclipse</h2>
<p>To build from Eclipse, make sure that you have configured it as described in
<a href="../../Getting_Started/html/index.html">"Getting Started."</a> If you
wish to build using the default <code>ndk-build</code> command, with no
options, you can just build your project just as you would any Android project.
To add the options described above to the <code>ndk-build</code> command that
Eclipse issues, follow these steps:</p>
<ol type="1">
<li>Right-click your project.</li>
<li>Select <code>Preferences</code>.</li>
<li>Click next to <code>C/C++ Build</code>.</li>
<li>Uncheck <code>Use default build command</code>.</li>
<li>Enter the entire build string as if you were typing it on the command
line.</li>
<li>Click <code>OK</code>.</li>
</ol>
Figure 1 shows the string as typed in the <b>Build command</b> field.<br>
<br>
<div class="image">
<img src="./images/NDK_build_string.png"  alt="setting where NDK lives"
align="left" width="660"/>
</div>
<p style="clear:both"><b>Figure 1.</b> Specifying a debug build from within
Eclipse</p>
<p><a class="anchor" id="dvr"></a> </p>
<h3>Debuggable versus Release builds</h3>
<p>Use the <code>NDK_DEBUG</code> parameter in conjunction with
AndroidManifest.xml to control whether to perform a debug or release build,
optimization-related behavior, and inclusion of symbols. Table 1 shows the
results of each possible combination of settings.</p>
<p><em>Table 1.</em> Results of <code>NDK_DEBUG</code> (command line) and
<code>android:debuggable</code> (manifest) combinations.</p>
<table class="doxtable">
<tr>
<th></th><th>NDK_DEBUG=0 </th><th>NDK_DEBUG=1</th><th>NDK_DEBUG not specified
</th></tr>
<tr>
<td>android:debuggble="true" </td><td>Debug; Symbols; Optimized*1
</td><td>Debug; Symbols; Not optimized*2 </td><td>(same as NDK_DEBUG=1)
</td></tr>
<tr>
<td>android:debuggable="false"</td><td>Release; Symbols; Optimized
</td><td>Release; Symbols; Not optimized</td><td>Release; No symbols;
Optimized*3 </td></tr>
</table>
<p>*1: Useful for profiling.<br/>
 *2: Default for running ndk-gdb.<br/>
 *3: Default mode.<br/>
 </p>
<pre class="fragment">Note

NDK_DEBUG=1 is the equivalent of APP_OPTIM= debug in Application.mk, and
complies with the GCC -O0 option. NDK_DEBUG=0 is the equivalent of APP_OPTIM=
release, and complies with GCC -O2. For more information about `APP_OPTIM`, see
the Application.mk section.
</pre><p>The syntax on the command line is, for example: </p>
<pre class="fragment">$ ndk-build NDK_DEBUG=1
</pre><p>In the <code>AndroidManifest.xml file</code>, the syntax resembles the
following: </p>
<pre class="fragment">&lt;application android:label="@string/app_name"
android:debuggable="true"&gt;
</pre><p> <span><br/>
</span> </p>
<pre class="fragment">Important Note:
If you use the build tools of SDK r8 (or higher), you need not need touch your
AndroidManifest.xml file at all: Building a debug package (e.g. with ant debug
or the corresponding option of the ADT plugin) causes the tool automatically to
pick the native debug files generated with NDK_DEBUG=1.
</pre><p><a class="anchor" id="6432"></a> </p>
<h2>64-bit and 32-bit toolchains</h2>
<p>Some toolchains come with both 64-bit and 32-bit versions. For example,
directories <code>&lt;ndk&gt;/toolchain/&lt;name&gt;/prebuilt/</code> and
<code>&lt;ndk&gt;/prebuilt/</code> may contain both <code>linux-x86</code> and
<code>linux-x86_64</code> folders for Linux tools in 32-bit and 64-bit modes,
respectively. The ndk-build script automatically chooses a 64-bit version of
the toolchain if the host OS supports it. You can force the use of a 32-bit
toolchain by using <code>NDK_HOST_32BIT=1</code> either in your environment or
on the <code>ndk-build</code> command line.</p>
<p>Note that 64-bit tools utilize host resources better (faster, handle larger
programs, etc), and they can still generate 32-bit binaries for Android.</p>
<p><a class="anchor" id="req"></a> </p>
<h2>Requirements</h2>
<p>You need GNU Make 3.81 or later to use 'ndk-build' or the NDK in general.
The build scripts will detect a non-compliant Make tool, and generate an error
message.</p>
<p>If you have GNU Make 3.81 installed, but the default <code>make</code>
command doesn’t launch it, define GNUMAKE in your environment to point to it
before launching 'ndk-build'. For example: </p>
<pre class="fragment">$ export GNUMAKE=/usr/local/bin/gmake
$ ndk-build
</pre><p>Adapt to your shell and GNU Make 3.81 installation location.</p>
<p>You may override other host prebuilt tools in $NDK/prebuilt/&lt;OS&gt;/bin/
with the following environment variables: </p>
<pre class="fragment">$ export NDK_HOST_AWK=&lt;path-to-awk&gt;

$ export NDK_HOST_ECHO=&lt;path-to-echo&gt;

$ export NDK_HOST_CMP=&lt;path-to-cmp&gt; </pre> </div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Sun Jun 22 2014 15:25:44 for NDK
Programmer&#39;s Guide by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.5 </li>
  </ul>
</div>
</body>
</html>
